---
type: integration
title: '@astrojs/netlify'
description: '@astrojs/netlify SSR 어댑터를 사용하여 Astro 프로젝트를 배포하는 방법을 알아보세요.'
githubIntegrationURL: 'https://github.com/withastro/adapters/tree/main/packages/netlify/'
category: adapter
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';

이 어댑터를 사용하면 Astro가 [`hybrid` 또는 `server` 렌더링된 사이트](/ko/basics/rendering-modes/#요청-시-렌더링)를 [Netlify](https://www.netlify.com/)에 배포할 수 있습니다.

Astro를 [정적 사이트 빌더](/ko/basics/rendering-modes/#사전-렌더링)로 사용하는 경우 어댑터가 필요하지 않습니다.

[Netlify 배포 가이드](/ko/guides/deploy/netlify/)에서 Astro 사이트를 배포하는 방법을 알아보세요.

## 왜 Astro Netlify인가?

[Netlify](https://www.netlify.com/)는 GitHub 저장소에 직접 연결하여 사이트를 호스팅할 수 있는 배포 플랫폼입니다. 이 어댑터는 Astro 빌드 프로세스를 향상시켜 Netlify를 통한 배포용 프로젝트를 준비합니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

`astro add` 명령을 사용하여 Astro 프로젝트에서 SSR을 활성화하려면 Netlify 어댑터를 추가하세요.
그러면 `@astrojs/netlify`가 설치되고 `astro.config.mjs` 파일이 한 번에 적절하게 변경됩니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add netlify
  ```
  </Fragment>
</PackageManagerTabs>

### 수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트 종속성에 Netlify 어댑터를 설치합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/netlify
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/netlify
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 어댑터와 원하는 [주문형 렌더링 모드](/ko/basics/rendering-modes/#요청-시-렌더링)를 `astro.config.*` 파일에 추가하세요.

```js title="astro.config.mjs" ins={2, 6-7}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify(),
});
```

## 사용하기

[여기에서 전체 배포 가이드를 읽어보세요.](/ko/guides/deploy/netlify/)

지침에 따라 사이트를 [로컬로 빌드](/ko/guides/deploy/#사이트를-로컬로-빌드)하세요. 빌드 후에는 `.netlify/functions-internal/` 폴더의 [Netlify Functions](https://docs.netlify.com/functions/overview/)과 `.netlify/edge-functions/` 폴더의 [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/)을 모두 포함하는 `.netlify/` 폴더가 생성됩니다.

사이트를 배포하려면 [Netlify CLI](https://docs.netlify.com/cli/get-started/)를 설치하고 다음을 실행하세요.

```sh
netlify deploy
```

[Astro의 Netlify 블로그 게시물](https://www.netlify.com/blog/how-to-deploy-astro/)과 [Netlify 문서](https://docs.netlify.com/integrations/frameworks/astro/)는 이 통합을 사용하여 Netlify에 배포하는 방법에 대한 자세한 정보를 제공합니다.

### 사이트에서 에지 컨텍스트에 액세스하기

Netlify Edge Functions는 사용자 IP, 지리적 위치 데이터, 쿠키 등 요청에 대한 메타데이터를 포함하는 [컨텍스트 객체](https://docs.netlify.com/edge-functions/api/#netlify-specific-context-object)를 제공합니다.

이는 `Astro.locals.netlify.context` 객체를 통해 액세스할 수 있습니다.

```astro
---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Hello there, friendly visitor from {city}!</h1>
```

TypeScript를 사용하는 경우 `NetlifyLocals`를 사용하도록 `src/env.d.ts`를 업데이트하여 적절한 타입을 얻을 수 있습니다.

```ts title="src/env.d.ts"
/// <reference path="../.astro/types.d.ts" />
/// <reference types="astro/client" />

type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals;

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}
```

사전 렌더링된 페이지에서는 사용할 수 없습니다.

### Edge Functions에서 Astro 미들웨어 실행

모든 Astro 미들웨어는 빌드 시 사전 렌더링된 페이지에 적용되고 런타임 시 주문형 렌더링 페이지에 적용됩니다.

사전 렌더링된 페이지에 대한 리디렉션, 액세스 제어 또는 사용자 정의 응답 헤더를 구현하려면 [`edgeMiddleware` 옵션](/ko/reference/adapter-reference/#edgemiddleware)을 활성화하여 Netlify Edge Functions에서 미들웨어를 실행하세요.

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true,
  }),
});
```

`edgeMiddleware`가 활성화되면 에지 함수는 정적 자산, 사전 렌더링된 페이지, 주문형 렌더링된 페이지를 포함한 모든 요청에 ​​대해 미들웨어 코드를 실행합니다.

주문형 렌더링된 페이지의 경우 `context.locals` 객체는 JSON을 사용하여 직렬화되어 렌더링을 수행하는 서버리스 함수의 헤더로 전송됩니다. 보안 조치로서 서버리스 함수는 생성된 에지 함수에서 발생하지 않는 한 `403 Forbidden` 응답이 포함된 요청 처리를 거부합니다.

### Netlify 이미지 CDN 지원

이 어댑터는 기본적으로 [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview/)을 사용하여 빌드 시간에 영향을 주지 않고 즉시 이미지를 변환합니다.
내부적으로는 [Astro 이미지 서비스](/ko/reference/image-service-reference/)를 사용하여 구현됩니다.

Netlify의 Image CDN 원격 이미지 최적화를 선택 해제하려면 `imageCDN` 옵션을 사용하세요.

```js title="astro.config.mjs" ins={8}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    imageCDN: false,
  }),
});
```

다른 도메인에서 호스팅되는 이미지를 사용하는 경우 [`image.domains`](/ko/reference/configuration-reference/#imagedomains) 또는 [`image.remotePatterns`](/ko/reference/configuration-reference/#imageremotepatterns) 구성 옵션을 사용하여 도메인 또는 URL 패턴을 승인해야 합니다.


```js title="astro.config.mjs" ins={8-10}
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    output: 'server',
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});
```

자세한 내용은 [원격 이미지 승인 가이드](/ko/guides/images/#원격-이미지-승인)를 참조하세요. 여러분의 사이트와 동일한 도메인에 호스팅된 이미지에는 필요하지 않습니다.

### Netlify 어댑터를 사용하는 정적 사이트

Netlify에서 호스팅되는 정적 사이트 (`output: 'static'`)의 경우 일반적으로 어댑터가 필요하지 않습니다. 그러나 일부 배포 기능은 어댑터를 통해서만 사용할 수 있습니다.

Netlify의 [이미지 서비스](#netlify-이미지-cdn-지원)를 사용하고 구성하려면 정적 사이트에서 이 어댑터를 설치해야 합니다.

Astro 구성에서 `redirects` 구성을 사용하는 경우 Netlify 어댑터를 사용하여 이를 적절한 `_redirects` 형식으로 변환할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify/static';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});
```

`astro build`를 실행하면 `dist/_redirects` 파일이 생성됩니다. Netlify는 이를 사용하여 프로덕션에서 페이지를 적절하게 라우팅합니다.

:::note
수동 리디렉션을 위해 `public/_redirects` 파일을 계속 포함할 수 있습니다. 리디렉션 구성에서 지정한 모든 리디렉션은 자신의 리디렉션 끝에 추가됩니다.
:::

### 캐싱 페이지

동적 콘텐츠가 없는 주문형 렌더링 페이지를 캐시하여 성능을 향상하고 리소스 사용량을 줄일 수 있습니다.
어댑터에서 `cacheOnDemandPages` 옵션을 활성화하면 서버에서 렌더링된 모든 페이지를 최대 1년 동안 캐시합니다.

```ts title="astro.config.mjs"
export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});
```

응답에 캐싱 헤더를 추가하여 페이지별로 변경할 수 있습니다.

```astro title="pages/index.astro"
---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>
```

[세밀한 캐시 제어](https://www.netlify.com/blog/swr-and-fine-grained-cache-control/)를 통해 Netlify는 `CDN-Cache-Control` 또는 `Vary`와 같은 표준 캐싱 헤더를 지원합니다.
time to live (TTL) 또는 stale while revalidate (SWR) 캐싱 등의 구현에 대해 알아보기 위해 문서를 참조하세요: https://docs.netlify.com/platform/caching

## 예시

- [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter)는 README에서 예시와 가이드를 제공합니다.

- 더 많은 예시를 보려면 [GitHub에서 Astro Netlify 프로젝트를 찾아보세요](https://github.com/search?q=path%3A**%2Fastro.config.mjs+%40astrojs%2Fnetlify&type=code)!

[astro-integration]: /ko/guides/integrations-guide/
